---
title: Start
description: Start a pgroll migration
---

## Command

```
$ pgroll start sql/03_add_column.yaml
```

This starts the migration defined in the `sql/03_add_column.yaml` file.

After starting a migration there will be two schema versions in the database; one for the old schema before the migration (e.g. `public_02_create_table`) and one for the new version with the schema changes (e.g. `public_03_add_column`). Each of these schemas merely contains views on the tables in the `public` schema.

### Using `pgroll start` with the `--complete` flag

A migration can be started and completed with one command by specifying the `--complete` flag:

```
$ pgroll start sql/03_add_column.yaml --complete
```

This is equivalent to running `pgroll start` immediately followed by `pgroll complete`.

<Warning>
  Using the `--complete` flag is appropriate only when there are no applications
  running against the old database schema. In most cases, the recommended
  workflow is to run `pgroll start`, then gracefully shut down old applications
  before running `pgroll complete` as a separate step.
</Warning>

## Backfill Configuration

When migrations involve backfilling data (such as adding a `NOT NULL` constraint to an existing column), the backfill process can be controlled using these flags:

- `--backfill-batch-size`: Number of rows backfilled in each batch (default: 1000)
- `--backfill-batch-delay`: Duration of delay between each batch, e.g., "1s", "1000ms" (default: 0s)

```
$ pgroll migrate examples/ --backfill-batch-size 500 --backfill-batch-delay 100ms
```

These options help manage the performance impact of large backfill operations by processing data in smaller batches with optional delays between batches.

## Existing Database Schema

If you attempt to run `pgroll start` against a database that has existing tables but no migration history, the command will fail with an error message. In this case, you should first run `pgroll baseline` to establish a baseline migration that captures the current schema state before starting any new migrations.
